/* Foley C# Utilities
 * Copyright (C)2002 Rodney S. Foley
 *  
 * This program is free software; you can 
 * redistribute it and/or modify it under the 
 * terms of the GNU General Public License as 
 * published by the Free Software Foundation; 
 * either version 2 of the License, or (at your 
 * option) any later version.
 * 
 * This program is distributed in the hope that 
 * it will be useful, but WITHOUT ANY WARRANTY; 
 * without even the implied warranty of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR 
 * PURPOSE. See the GNU General Public License 
 * for more details.
 * 
 * You should have received a copy of the GNU 
 * General Public License along with this 
 * program; if not, write to: 
 * 
 *		Free Software Foundation, Inc., 
 *		59 Temple Place, Suite 330, 
 *		Boston, MA 02111-1307 USA
 * 
 *					- or -
 * 
 * http://opensource.org/licenses/gpl-license.php
 */

using System;
using System.Collections;

namespace Foley.Utilities.Collections
{
	/// <summary>
	/// Represents an enhanced version of the <see cref="IList"/> interface.
	/// </summary>
	public interface IList2 : IList, ICollection2
	{		
		/// <summary>
		/// When implemented by a class, adds the elements of
		/// the specified <see cref="ICollection"/> to the end of the list.
		/// </summary>
		/// <param name="collection">
		/// The <see cref="ICollection"/> whose elements are to be added to
		/// the list.
		/// </param>
		/// <returns>
		/// <c>true</c> if the list is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The list is read-only.</para>
		/// -or-
		/// <para>The list has a fixed size.</para>
		/// </exception>
		bool Add(ICollection collection);

		/// <summary>
		/// When implemented by a class, determines whether all the elements
		/// in the specified <paramref name="collection"/> are contained
		/// in the <see cref="IList"/> contains.
		/// </summary>
		/// <param name="collection">
		/// The <see cref="ICollection"/> whose elements are to be added
		/// to the end of the list.
		/// </param>
		/// <returns>
		/// <c><c>true</c></c> if all the elements of the <see cref="ICollection"/> 
		/// are found in the list; otherwise, <c>false</c>.
		/// </returns>
		bool Contains(ICollection collection);

		/// <summary>
		/// When implemented by a class, inserts an object to the list at the 
		/// specified position.
		/// </summary>
		/// <param name="index">
		/// The zero-based index at which value should be inserted.
		/// </param>
		/// <param name="value">
		/// The object to insert into the list. 
		/// </param>
		/// <returns>
		/// <c>true</c> if the list is modified; otherwise <c>false</c>.
		/// </returns>
		/// <remarks>
		/// This method hides the <see cref="IList"/> method that returns 
		/// void.  You may want to do an explicit interface method
		/// implementation for the <see cref="IList"/> version to be 
		/// completely compatible.
		/// </remarks>
		/// <exception cref="NotSupportedException">
		/// <para>The list is read-only.</para>
		/// -or-
		/// <para>The list has a fixed size.</para>
		/// </exception>
		new bool Insert(int index, object value);

		/// <summary>
		/// When implemented by a class, inserts the elements of the 
		/// <see cref="ICollection"/> to the list at the specified position.
		/// </summary>
		/// <param name="index">
		/// The zero-based <paramref name="index"/> at which 
		/// <paramref name="collection"/> should be inserted.
		/// </param>
		/// <param name="collection">
		/// The <see cref="ICollection"/> whose elements are to be added to 
		/// the list.
		/// </param>
		/// <returns>
		/// <c>true</c> if the list is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The list is read-only.</para>
		/// -or-
		/// <para>The list has a fixed size.</para>
		/// </exception>
		bool Insert(int index, ICollection collection);

		/// <summary>
		/// When implemented by a class, determines the index of the last 
		/// occurrence of the specific object in the list.
		/// </summary>
		/// <param name="value">
		/// The object to locate in the list.
		/// </param>
		/// <returns>
		/// The index of the last occurrence of the value 
		/// if found in the list; otherwise, -1.
		/// </returns>
		int LastIndexOf(object value);

		/// <summary>
		/// When implemented by a class, returns an <see cref="IEnumerator"/> 
		/// that can iterate through the list that starts at the specified 
		/// position.
		/// </summary>
		/// <param name="index">
		/// Starting <paramref name="index"/> in the list for the begining of 
		/// the <see cref="IEnumerator"/>.
		/// </param>
		/// <returns>
		/// An <see cref="IEnumerator"/> that can be used to iterate 
		/// through the list.
		/// </returns>
		IEnumerator GetEnumerator(int index);

		/// <summary>
		/// When implemented by a class, removes the first occurrence of a
		/// specific object from the list.
		/// </summary>
		/// <param name="value">
		/// The object to remove from the list. 
		/// </param>
		/// <returns>
		/// <c>true</c> if the list is modified; otherwise <c>false</c>.
		/// </returns>
		/// <remarks>
		/// This method hides the <see cref="IList"/> method that returns void. 
		/// You may want to do an explicit interface method implementation for
		/// the <see cref="IList"/> version to be completely 
		/// compatible.
		/// </remarks>
		/// <exception cref="NotSupportedException">
		/// <para>The list is read-only.</para>
		/// -or-
		/// <para>The list has a fixed size.</para>
		/// </exception>
		new bool Remove(object value);

		/// <summary>
		/// When implemented by a class, removes the specified
		/// number of the elements starting at the position specified.
		/// </summary>
		/// <param name="index">
		/// Starting <paramref name="index"/> for removing elements from the
		/// list.
		/// </param>
		/// <param name="count">
		/// The number of elements to remove from the list.
		/// </param>
		/// <returns>
		/// <c>true</c> if the list is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The list is read-only.</para>
		/// -or-
		/// <para>The list has a fixed size.</para>
		/// </exception>
		bool Remove(int index, int count);
		
		/// <summary>
		/// When implemented by a class, removes the first 
		/// occurrence of each element of the specified 
		/// <see cref="ICollection"/> from the list.
		/// </summary>
		/// <param name="collection">
		/// The <see cref="ICollection"/> used to determine what 
		/// elements to remove from the list.
		/// </param>
		/// <returns>
		/// <c>true</c> if the list is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The list is read-only.</para>
		/// -or-
		/// <para>The list has a fixed size.</para>
		/// </exception>
		bool Remove(ICollection collection);

		/// <summary>
		/// When implemented by a class, removes the element
		/// at the specified position from the list.
		/// </summary>
		/// <param name="index">
		/// The <paramref name="index"/> of the element to remove from the 
		/// list.
		/// </param>
		/// <returns>
		/// <c>true</c> if the list is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The list is read-only.</para>
		/// -or-
		/// <para>The list has a fixed size.</para>
		/// </exception>
		new bool RemoveAt(int index);

		/// <summary>
		/// When implemented by a class, retains the first
		/// occurrence of each element of the specified
		/// <see cref="ICollection"/> from the list.
		/// </summary>
		/// <param name="collection">
		/// The <see cref="ICollection"/> used to determine what 
		/// elements to be retained in the list.
		/// </param>
		/// <returns>
		/// <c>true</c> if the list is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The list is read-only.</para>
		/// -or-
		/// <para>The list has a fixed size.</para>
		/// </exception>
		bool Retain(ICollection collection);

		/// <summary>
		/// When implemented by a class, provides a view of
		/// the list with the specified number of the elements 
		/// starting at the position specified.
		/// </summary>
		/// <param name="index">
		/// Starting <paramref name="index"/> for the view of elements from
		/// the list.
		/// </param>
		/// <param name="count">
		/// The number of elements to include in the view of the list.
		/// </param>
		/// <returns>
		/// A view of list.
		/// </returns>
		/// <remarks>
		/// The list that is returned is just a view, it is still backed
		/// by the orignal list.  Any changes you make to it will be 
		/// reflected in the orignal list.
		/// </remarks>
		IList SubList(int index, int count);
	}
}
